<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Using PHP and DTrace</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="features.dtrace.introduction.html">Introduction to PHP and DTrace</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="features.dtrace.systemtap.html">Using SystemTap with PHP DTrace Static Probes</a></div>
 <div class="up"><a href="features.dtrace.html">DTrace Dynamic Tracing</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="features.dtrace.dtrace" class="sect1">
  <h2 class="title">Using PHP and DTrace</h2>
  <p class="para">
   PHP can be configured with DTrace static probes on platforms that
   support DTrace Dynamic Tracing.
  </p>

  <div class="sect2" id="features.dtrace.install">
   <h3 class="title">Configuring PHP for DTrace Static Probes</h3>

   <p class="para">
    Refer to external platform specific documentation for enabling
    operating system DTrace support.  For example, on Oracle Linux
    boot a UEK3 kernel and do:

    <div class="informalexample">
     <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
#&nbsp;modprobe&nbsp;fasttrap<br />#&nbsp;chmod&nbsp;666&nbsp;/dev/dtrace/helper</span>
</code></div>
     </div>

    </div>
   </p>
   <p class="para">
    Instead of using <em>chmod</em>, you could instead use an
    ACL package rule to limit device access to a specific user.
   </p>

   <p class="para">
    Build PHP with the <em>--enable-dtrace</em> configuration parameter:
    <div class="informalexample">
     <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
#&nbsp;./configure&nbsp;--enable-dtrace&nbsp;...<br />#&nbsp;make<br />#&nbsp;make&nbsp;install</span>
</code></div>
     </div>

    </div>
   </p>
   <p class="para">
    This enables the static probes in core PHP.  Any PHP extensions
    that provide their own probes should be built separately as shared
    extensions.
   </p>
  </div>

  <div class="sect2" id="features.dtrace.static-probes">
  <h3 class="title">DTrace Static Probes in Core PHP</h3>
  <table class="doctable table">
   <caption><strong>The following static probes are available in PHP</strong></caption>
   
    <thead>
     <tr>
      <th>Probe Name</th>
      <th>Probe Description</th>
      <th>Probe Arguments</th>
     </tr>

    </thead>

    <tbody class="tbody">
     <tr>
      <td><em>request-startup</em></td>
      <td>Fires when a request starts.</td>
      <td>char *<var class="varname"><var class="varname">file</var></var>, char *<var class="varname"><var class="varname">request_uri</var></var>, char *<var class="varname"><var class="varname">request_method</var></var></td>
     </tr>

     <tr>
      <td><em>request-shutdown</em></td>
      <td>Fires when a request shutdown.</td>
      <td>char *<var class="varname"><var class="varname">file</var></var>, char *<var class="varname"><var class="varname">request_uri</var></var>, char *<var class="varname"><var class="varname">request_method</var></var></td>
     </tr>

     <tr>
      <td><em>compile-file-entry</em></td>
      <td>Fires when the compilation of a script starts.</td>
      <td>char *<var class="varname"><var class="varname">compile_file</var></var>, char *<var class="varname"><var class="varname">compile_file_translated</var></var></td>
     </tr>

     <tr>
      <td><em>compile-file-return</em></td>
      <td>Fires when the compilation of a script finishes.</td>
      <td>char *<var class="varname"><var class="varname">compile_file</var></var>, char *<var class="varname"><var class="varname">compile_file_translated</var></var></td>
     </tr>

     <tr>
      <td><em>execute-entry</em></td>
      <td>Fires when an opcode array is to be executed.  For
      example, it fires on function calls, includes, and generator
      resumes.</td>
      <td>char *<var class="varname"><var class="varname">request_file</var></var>, int <var class="varname"><var class="varname">lineno</var></var></td>
     </tr>

     <tr>
      <td><em>execute-return</em></td>
      <td>Fires after execution of an opcode array.</td>
      <td>char *<var class="varname"><var class="varname">request_file</var></var>, int <var class="varname"><var class="varname">lineno</var></var></td>
     </tr>

     <tr>
      <td><em>function-entry</em></td>
      <td>Fires when the PHP engine enters a PHP function or method call.</td>
      <td>char *<var class="varname"><var class="varname">function_name</var></var>, char *<var class="varname"><var class="varname">request_file</var></var>, int <var class="varname"><var class="varname">lineno</var></var>, char *<var class="varname"><var class="varname">classname</var></var>, char *<var class="varname"><var class="varname">scope</var></var></td>
     </tr>

     <tr>
      <td><em>function-return</em></td>
      <td>Fires when the PHP engine returns from a PHP function or method call.</td>
      <td>char *<var class="varname"><var class="varname">function_name</var></var>, char *<var class="varname"><var class="varname">request_file</var></var>, int <var class="varname"><var class="varname">lineno</var></var>, char *<var class="varname"><var class="varname">classname</var></var>, char *<var class="varname"><var class="varname">scope</var></var></td>
     </tr>

     <tr>
      <td><em>exception-thrown</em></td>
      <td>Fires when an exception is thrown.</td>
      <td>char *<var class="varname"><var class="varname">classname</var></var></td>
     </tr>

     <tr>
      <td><em>exception-caught</em></td>
      <td>Fires when an exception is caught.</td>
      <td>char *<var class="varname"><var class="varname">classname</var></var></td>
     </tr>

     <tr>
      <td><em>error</em></td>
      <td>Fires when an error occurs, regardless of the <a href="errorfunc.configuration.html#ini.error-reporting" class="link">error_reporting</a> level.</td>
      <td>char *<var class="varname"><var class="varname">errormsg</var></var>, char *<var class="varname"><var class="varname">request_file</var></var>, int <var class="varname"><var class="varname">lineno</var></var></td>
     </tr>

    </tbody>
   
  </table>

  <p class="para">
   PHP extensions may also have additional static probes.
  </p>
  </div>

  <div class="sect2" id="features.dtrace.list-probes">
   <h3 class="title">Listing DTrace Static Probes in PHP</h3>
   <p class="para">
    To list available probes, start a PHP process and then run:
    <div class="informalexample">
     <div class="example-contents">
<div class="cdata"><pre>
# dtrace -l
</pre></div>
     </div>

    </div>
   </p>

   <p class="para">
    The output will be similar to:
    <div class="informalexample">
     <div class="example-contents">
<div class="cdata"><pre>
   ID   PROVIDER            MODULE                          FUNCTION NAME
   [ . . . ]
    4   php15271               php               dtrace_compile_file compile-file-entry
    5   php15271               php               dtrace_compile_file compile-file-return
    6   php15271               php                        zend_error error
    7   php15271               php  ZEND_CATCH_SPEC_CONST_CV_HANDLER exception-caught
    8   php15271               php     zend_throw_exception_internal exception-thrown
    9   php15271               php                 dtrace_execute_ex execute-entry
   10   php15271               php           dtrace_execute_internal execute-entry
   11   php15271               php                 dtrace_execute_ex execute-return
   12   php15271               php           dtrace_execute_internal execute-return
   13   php15271               php                 dtrace_execute_ex function-entry
   14   php15271               php                 dtrace_execute_ex function-return
   15   php15271               php              php_request_shutdown request-shutdown
   16   php15271               php               php_request_startup request-startup
</pre></div>
     </div>

    </div>
   </p>

   <p class="para">
    The Provider column values consist of <em>php</em> and
    the process id of the currently running PHP process.
   </p>

   <p class="para">
    If the Apache web server is running, the module name might be, for
    example, <var class="filename">libphp5.so</var>, and there would be
    multiple blocks of listings, one per running Apache process.
   </p>

   <p class="para">
    The Function column refers to PHP&#039;s internal C implementation
    function names where each provider is located.
   </p>

   <p class="para">
    If a PHP process is not running, then no PHP probes will be shown.
   </p>
  </div>

  <div class="sect2" id="features.dtrace.examples">
   <h3 class="title">DTrace with PHP Example</h3>
   <p class="para">
    This example shows the basics of the DTrace D scripting language.
    <div class="example" id="example-376">
     <p><strong>Example #1 <var class="filename">all_probes.d</var> for tracing all PHP Static Probes with DTrace</strong></p>
     <div class="example-contents">
<div class="cdata"><pre>
#!/usr/sbin/dtrace -Zs

#pragma D option quiet

php*:::compile-file-entry
{
    printf(&quot;PHP compile-file-entry\n&quot;);
    printf(&quot;  compile_file              %s\n&quot;, copyinstr(arg0));
    printf(&quot;  compile_file_translated   %s\n&quot;, copyinstr(arg1));
}

php*:::compile-file-return
{
    printf(&quot;PHP compile-file-return\n&quot;);
    printf(&quot;  compile_file              %s\n&quot;, copyinstr(arg0));
    printf(&quot;  compile_file_translated   %s\n&quot;, copyinstr(arg1));
}

php*:::error
{
    printf(&quot;PHP error\n&quot;);
    printf(&quot;  errormsg                  %s\n&quot;, copyinstr(arg0));
    printf(&quot;  request_file              %s\n&quot;, copyinstr(arg1));
    printf(&quot;  lineno                    %d\n&quot;, (int)arg2);
}

php*:::exception-caught
{
    printf(&quot;PHP exception-caught\n&quot;);
    printf(&quot;  classname                 %s\n&quot;, copyinstr(arg0));
}

php*:::exception-thrown
{
    printf(&quot;PHP exception-thrown\n&quot;);
    printf(&quot;  classname                 %s\n&quot;, copyinstr(arg0));
}

php*:::execute-entry
{
    printf(&quot;PHP execute-entry\n&quot;);
    printf(&quot;  request_file              %s\n&quot;, copyinstr(arg0));
    printf(&quot;  lineno                    %d\n&quot;, (int)arg1);
}

php*:::execute-return
{
    printf(&quot;PHP execute-return\n&quot;);
    printf(&quot;  request_file              %s\n&quot;, copyinstr(arg0));
    printf(&quot;  lineno                    %d\n&quot;, (int)arg1);
}

php*:::function-entry
{
    printf(&quot;PHP function-entry\n&quot;);
    printf(&quot;  function_name             %s\n&quot;, copyinstr(arg0));
    printf(&quot;  request_file              %s\n&quot;, copyinstr(arg1));
    printf(&quot;  lineno                    %d\n&quot;, (int)arg2);
    printf(&quot;  classname                 %s\n&quot;, copyinstr(arg3));
    printf(&quot;  scope                     %s\n&quot;, copyinstr(arg4));
}

php*:::function-return
{
    printf(&quot;PHP function-return\n&quot;);
    printf(&quot;  function_name             %s\n&quot;, copyinstr(arg0));
    printf(&quot;  request_file              %s\n&quot;, copyinstr(arg1));
    printf(&quot;  lineno                    %d\n&quot;, (int)arg2);
    printf(&quot;  classname                 %s\n&quot;, copyinstr(arg3));
    printf(&quot;  scope                     %s\n&quot;, copyinstr(arg4));
}

php*:::request-shutdown
{
    printf(&quot;PHP request-shutdown\n&quot;);
    printf(&quot;  file                      %s\n&quot;, copyinstr(arg0));
    printf(&quot;  request_uri               %s\n&quot;, copyinstr(arg1));
    printf(&quot;  request_method            %s\n&quot;, copyinstr(arg2));
}

php*:::request-startup
{
    printf(&quot;PHP request-startup\n&quot;);
    printf(&quot;  file                      %s\n&quot;, copyinstr(arg0));
    printf(&quot;  request_uri               %s\n&quot;, copyinstr(arg1));
    printf(&quot;  request_method            %s\n&quot;, copyinstr(arg2));
}
</pre></div>
     </div>

    </div>
   </p>

   <p class="para">
    This script uses the <em>-Z</em> option to
    <var class="filename">dtrace</var>, allowing it to be run when there is no
    PHP process executing.  If this option were omitted the script
    would immediately terminate because it knows none of the probes to
    be monitored are in existence.
   </p>

   <p class="para">
    The script traces all core PHP static probe points throughout the
    duration of a running PHP script. Run the D script:
    <div class="informalexample">
     <div class="example-contents">
<div class="cdata"><pre>
# ./all_probes.d
</pre></div>
     </div>

    </div>
   </p>

   <p class="para">
    Run a PHP script or application.  The monitoring D script will
    output each probe&#039;s arguments as it fires.
   </p>

   <p class="para">
    When monitoring is complete, the D script can be terminated with a
    <em>^C</em>.
   </p>

   <p class="para">
    On multi-CPU machines the probe ordering might not appear to be
    sequential. This depends on which CPU was processing the probes,
    and how threads migrate across CPUs.  Displaying probe time stamps
    will help reduce confusion, for example:
    <div class="informalexample">
     <div class="example-contents">
<div class="cdata"><pre>
php*:::function-entry
{
      printf(&quot;%lld: PHP function-entry &quot;, walltimestamp);
      [ . . .]
}
</pre></div>
     </div>

    </div>
   </p>
  </div>

  <div class="sect2" id="features.dtrace.references">
   <h3 class="title">See Also</h3>
   <ul class="simplelist">
    <li class="member"><a href="oci8.dtrace.html" class="link">OCI8 and DTrace Dynamic Tracing</a></li>
   </ul>
  </div>
 </div><hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="features.dtrace.introduction.html">Introduction to PHP and DTrace</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="features.dtrace.systemtap.html">Using SystemTap with PHP DTrace Static Probes</a></div>
 <div class="up"><a href="features.dtrace.html">DTrace Dynamic Tracing</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
